home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / tvdmx.exe / README.DOC < prev    next >
Encoding:
Text File  |  1992-07-16  |  38.1 KB  |  988 lines
  1.  
  2.   tvDMX  version 1.5  (c) 1992  Randolph Beck
  3.   =====
  4.  
  5.   This is a shareware product and may be distributed and copied for free.
  6.  
  7.   Users must register their copy by sending $20 to:
  8.  
  9.                              Randolph Beck
  10.                              tvDMX Registration
  11.                              P.O. Box  56-0487
  12.                              Orlando, FL 32856-0487
  13.  
  14.   Please include any questions or comments.  Registered users will receive
  15.   a diskette with the most recent version and additional documentation.
  16.   Registered users of previous versions may upgrade to this version free.
  17.   CompuServe members may contact the author at CIS: 72361,753.
  18.  
  19.  
  20.  
  21.          Page 1.     tvDMX OVERVIEW                                                    
  22.                          Keystroke Philosophy
  23.  
  24.          Page 2.     tvDMX CONCEPTS                                                    
  25.                          The Data-Formatting Template
  26.  
  27.          Page 3.     USING tvDMX IN YOUR PROGRAMS                                      
  28.                          Data Windows
  29.                          Automatic Assignment Constructors
  30.                          Loading tvDMX Views from a Stream
  31.                          Using tvDMX as Field Editors
  32.  
  33.          Page 6.     ADVANCED FEATURES                                                 
  34.                          User Key Errors
  35.                          Hidden and Read-Only Fields
  36.                          Swapping Field Positions
  37.  
  38.          Page 7.     ASCENDANCY CHART                                                  
  39.  
  40.          Page 8.     UNITS                                                             
  41.  
  42.          Page 9.     DATA TEMPLATE CODES                                               
  43.                          Using Template Codes                    
  44.                          Template Control Codes
  45.  
  46.          Page 14.    FYI
  47.                          Important Virtual Methods
  48.                          External Database Access
  49.                          Global Functions in Units DMXGIZMA and tvGIZMA
  50.  
  51.          Page 17.    USER RESPONSE FORM                                                
  52.  
  53.   tvDMX OVERVIEW                                                      Page 1
  54.   ==============
  55.  
  56.   This project was originally undertaken to enable programmers to quickly
  57.   design a browse-like data entry screen which users could operate in a
  58.   natural and intuitive way.  It was completely redesigned for Turbo Vision.
  59.  
  60.   The object-oriented framework of tvDMX can be extended to access any form
  61.   of data structure (including dBASE files and Streams and Collections).
  62.  
  63.   tvDMX display formats use picture templates and grant the programmer full
  64.   control over the appearance of each field.
  65.  
  66.   Features:
  67.         *  programmable display formats for the major Pascal data types
  68.         *  containment within a Turbo Vision scrolling view
  69.         *  virtual methods provide maximum flexibility
  70.         *  record structure and display format can be set at run-time
  71.         *  hidden and read-only fields
  72.         *  field display position order can differ from physical order
  73.         *  reports can be generated for the data in views
  74.  
  75.   This document should give a quick introduction to tvDMX.  Rather than
  76.   detail the inner workings, I decided to provide four sample programs
  77.   which you can examine:
  78.  
  79.   SAMPLES.PAS displays several windows:  Each with data in various formats.
  80.     Most of the scrolling data windows has an accompanying dialog window
  81.     which can be selected by pressing the <F2> key.  This will give you an
  82.     idea of what tvDMX can do.
  83.  
  84.   WORKSHOP.PAS is intended for your own experiments.  It will give you an
  85.     idea of how easy it is to create a data window.  WORKSHOP was written
  86.     so that you can easily modify the data structure and display formats.
  87.  
  88.   FILESHOP.PAS manages data on disk via a TDosStream object --to show that
  89.     tvDMX operations are not limited to data in RAM.
  90.  
  91.   DLGSHOP.PAS demonstrates how to integrate a tvDMX view into a dialog box.
  92.  
  93.   COLLECTR.PAS demonstrates how to manage data in a collection.
  94.  
  95.   The source code for each of these programs contains additional information
  96.   about its use and features.
  97.  
  98.                              Keystroke Philosophy
  99.                              --------------------
  100.  
  101.   Most keys work as you would expect.  In addition:  kbCtrlT deletes the
  102.   current field, and kbCtrlY deletes the current record.
  103.  
  104.   The kbLeft and kbRight keys normally move the field pointer from one
  105.   field to another.  Movement within a character field is permitted:
  106.  
  107.       1) After a character is entered into the field;
  108.       2) after kbIns, kbCtrlT or kbCtrlY is pressed; or
  109.       3) anytime the keyboard is not in INSERT mode.
  110.  
  111.   tvDMX CONCEPTS                                                      Page 2
  112.   ==============
  113.  
  114.  
  115.                          The Data-Formatting Template
  116.                          ----------------------------
  117.  
  118.   The default appearance of these views is usually column/row oriented.
  119.   You declare a record structure for the DMX initialization procedure in
  120.   a template string --which also determines the display format.
  121.   (You will see later how tvDMX can be used for field editors.)
  122.  
  123.   A RECORD of STRING [20], INTEGER, and REAL may use this format:
  124.            ' ssssssssssssssssssss | iiii | ($rrr,rrr.rr) '
  125.  
  126.   And that would present a record in this way:
  127.            ' Daniel D. Demo       │  154 │  $ 12,056.55  '
  128.  
  129.   The template string in this example was entirely in lower case.  If in
  130.   upper case, character-fields would be entered in upper case and
  131.   numeric-fields would be restricted to positive values.
  132.  
  133.   The data TYPE of each field is determined by the characters in the string.
  134.   All primary Pascal data types are supported:  BOOLEAN, BYTE, SHORTINT,
  135.   INTEGER, LONGINT, WORD, STRING, CHAR, arrays of CHAR, and REAL.  The
  136.   programmer only needs to alter this one template string when changing the
  137.   data structure.  (Template codes are listed on the Reference page.)
  138.  
  139.   You can switch to SINGLE, DOUBLE or EXTENDED reals by changing TYPE
  140.   TREALNUM in RSET.PAS.
  141.  
  142.  
  143.   A backslash ('\') may be used as a field delimiter, and is displayed as a
  144.   space character.  (Other delimiters can be devised as well --please refer
  145.   to the ^D control code.)
  146.  
  147.   The tilde ('~') character can be used to switch format-processing on and
  148.   off.  This makes it possible to separate the text-literals from format and
  149.   control codes:
  150.  
  151.       ' ~Name:~ ssssssssssssssssssss\ ~SSN:~ ###-##-#### '
  152.  
  153.     This is diplayed as:
  154.       ' Name: Daniel D. Demo        SSN: 012-34-5678 '
  155.  
  156.   USING tvDMX IN YOUR PROGRAMS                                        Page 3
  157.   ============================
  158.  
  159.                                  Data Windows
  160.                                  ------------
  161.  
  162.   Presumably you understand that a focused TScroller is owned by, and
  163.   operates within, an active TWindow.  The TScroller also has several
  164.   peer-views:  a TFrame and two TScrollBars.  If you wished, you could add
  165.   more views to display additional information.  This is how the
  166.   TDmxScroller object works, as well as its descendant TDmxEditor.
  167.  
  168.   (A TDmxScroller object displays data in a scrolling window, and a
  169.   TDmxEditor object adds the ability to edit the data.)
  170.  
  171.   Programmers can instantiate a TWindow view and insert a TDmxEditor object
  172.   just like using TScroller --with a few extra parameters. Then, for an
  173.   effective data window, field titles should be placed at the top, and a
  174.   record number indicator should be placed below.
  175.  
  176.   The TDmxWindow object (a descendant of TWindow) coordinates the entire
  177.   process of inserting these extra views.
  178.  
  179.   Initialization Syntax:
  180.  
  181.       constructor TDmxWindow.Init (
  182.                    var Bounds    : TRect;
  183.                        ATitle    : TTitleStr;
  184.                        ANumber   : Integer;
  185.                        ATemplate : String;
  186.                    var AData;
  187.                        BSize     : LongInt;
  188.                    var ALabels   : String;
  189.                        IndLen    : Integer);
  190.  
  191.     Bounds, ATitle and ANumber are the same parameters required for any
  192.       TWindow object.
  193.     ATemplate is a tvDMX data format template string.
  194.     AData refers to the data to be edited.  Note that your data is not
  195.       part of this object.
  196.     BSize is the size of the entire data structure.
  197.     ALabels is the string which labels the fields over the editor.
  198.     IndLen is the length of a record number indicator view (usually about
  199.       five to ten bytes).  The default indicator is placed just to the
  200.       left of the horizontal scroll bar.
  201.  
  202.  
  203.   Note:  Since descendant objects are crucial to programmers who wish to
  204.   build upon the framework of tvDMX, it should be understood that
  205.   descendants of TDmxWindow must be created to initialize your descendants
  206.   of TDmxEditor.  (Refer to the demo programs for sample usage.)
  207.  
  208.   The TDmxWindow.Init() constructor will first assign and construct two
  209.   auxiliary views, TDmxLabels and TDmxRecInd, which serve as a field title
  210.   display and a record number indicator.  This process is managed by virtual
  211.   methods in object TDmxWindow which may be overridden with new descendants.
  212.  
  213.                                                                       Page 4
  214.                       Automatic Assignment Constructors
  215.                       ---------------------------------
  216.  
  217.   Programmers who make extensive use of tvDMX descendants may which to avoid
  218.   using TDmxWindow objects and insert TDmxEditor views directly into TWindow
  219.   or TDialog window types.  Automatic assignment constructors were developed
  220.   to make this process easier.
  221.  
  222.   Normally, TDmxLabels and TDmxRecInd object types alternate constructors:
  223.  
  224.       constructor TDmxLabels.InitInsert (AOwner : PGroup; var ALabels );
  225.           ALabels refers to the String that displays field heading labels.
  226.  
  227.       constructor TDmxRecInd.InitInsert (AOwner : PGroup; Len : integer);
  228.           Len refers to the desired width of the indicator view.
  229.  
  230.   Both require a pointer to the window that it will be inserted into.  They
  231.   can use the size of that view to assign and position themselves.  The
  232.   view insertion is also automatic.
  233.  
  234.   WORKSHOP.PAS has been modified to use automatic insertion constructors
  235.   with a regular TWindow object.
  236.  
  237.  
  238.                       Loading tvDMX Views from a Stream
  239.                       ---------------------------------
  240.  
  241.   tvDMX objects have Load() constructors and Store() destructors that load
  242.   and store the object's fields.  But it would be impractical for the tvDMX
  243.   object to also retain the window's database because the data source can
  244.   vary, depending upon the application.  Therefore, two abstract virtual
  245.   methods --LoadData() and StoreData()-- must be overridden for storage on
  246.   streams:
  247.  
  248.       procedure LoadData (var S : TStream);  VIRTUAL;
  249.       procedure StoreData (var S : TStream);  VIRTUAL;
  250.  
  251.   LoadData() must set LongInt DataBlockSize with the size of the database
  252.   (in bytes, not records) and set Pointer WorkingData with the address of
  253.   the database.  It should be designed in a way that allows for the fact
  254.   that the database may have been removed or altered by another program
  255.   since the time this object was stored.
  256.  
  257.   StoreData() must save the database parameters in a way that it may be
  258.   reopened by LoadData().
  259.  
  260.     Note:  The LoadData() and StoreData() methods for object TInputFields
  261.            are already implemented, since their small amount of data are
  262.            easily streamed.
  263.  
  264.                                                                       Page 5
  265.                          Using tvDMX as Field Editors
  266.                          ----------------------------
  267.  
  268.   It is only natural that a descendant of TDmxEditor would be written to
  269.   serve as a replacement for the TInputLine object.
  270.  
  271.   Object TInputFields is a TDmxEditor derivative that:  1) Allocates memory
  272.   to hold the data fields;  2) Overrides the DataSize(), GetData() and
  273.   SetData() methods;  3) Uses a different palette suitable for Dialog boxes;
  274.   and 4) Has special handling of the cursor keys to operate more naturally
  275.   within a Dialog box.
  276.  
  277.   A special insertion function was written to measure and initialize it with
  278.   an accompanying TLabel object:
  279.  
  280.     function InsertField (Dialog     : PDialog;
  281.                           Col, Row   : Integer;
  282.                           Fmt        : Boolean;
  283.                           ALabel,
  284.                           ATemplate  : String)  : PView;
  285.  
  286.     Dialog is a pointer to the dialog window into which these views are
  287.       inserted.
  288.     Col and Row are the upper left corner of the label.
  289.     Fmt orientation of the tvDMX editor view, relative to the label:
  290.       If TRUE, then the editor view is below the label;  but
  291.       if FALSE, the editor view follows the label on same line.
  292.     ALabel is the string that will become the label.
  293.     ATemplate is the string that becomes the editor view.
  294.  
  295.  
  296.   This function returns a pointer to the TInputFields view.  Usually, the
  297.   pointer will be discarded (this unit is compiled with extended syntax so
  298.   that the function can be implemented as a procedure), but there will be
  299.   occasions when the pointer is needed.
  300.  
  301.     Examples:
  302.  
  303.       InsertField (Dialog, 5,2, TRUE,
  304.                    '~N~ame', 'SSSSSSSSSSSSSSSSSSSS');
  305.  
  306.       InsertField (Dialog, 5,5, FALSE,
  307.                    '~S~SN: ',  '###-##-####')^.HelpCtx := 1000;
  308.  
  309.       P := InsertField (Dialog, 5,6, FALSE,  '', '$rrr,rrr.rr ');
  310.            { note that a label is not required }
  311.  
  312.  
  313.   The dialog window examples in SAMPLES.PAS demonstrates the use and
  314.   operation of the InsertField() function.  Press <F2> for a dialog window.
  315.  
  316.   ADVANCED FEATURES                                                   Page 6
  317.   =================
  318.  
  319.                                User Key Errors
  320.                                ---------------
  321.  
  322.   Keys pressed that are out of range (eg: 'z' within numeric fields) will
  323.   generate cmDMX_WrongKey command events.  See tvGIZMA.PAS for examples.
  324.  
  325.  
  326.                          Hidden and Read-Only Fields
  327.                          ---------------------------
  328.  
  329.   Some programs use data with hidden fields.  (dBASE files require a leading
  330.   byte at the beginning of each record.)  And many programs use fields which
  331.   can be seen but not altered.  (This may be when the field is accessed by
  332.   the program and not by the user.)
  333.  
  334.   Both of these situations are handled by control codes in the template
  335.   string that mark fields as Hidden or Read-Only.
  336.  
  337.   Example: ^H + 'B' + #0 + ^R + ' iii |'...
  338.  
  339.            ^H + 'B' specifies a hidden BYTE field;
  340.            #0 marks a new field without a visible delimiter;
  341.            ^R marks the next field as a Read-Only integer;  and so on...
  342.  
  343.   Program users will recognize Read-Only fields because they have their own
  344.   color in the palette (when focused).
  345.  
  346.  
  347.                            Swapping Field Positions
  348.                            ------------------------
  349.  
  350.   Date fields are often arranged in Year-Month-Day order, but the
  351.   conventional display format is Month-Day-Year.  The ^P control code makes
  352.   it possible to display and edit fields in a different order than in which
  353.   they are physically organized.  This exchange is transparent to the user.
  354.  
  355.   Unit DMXGIZMA contains fldDATE, a string constant that uses the ^P code to
  356.   display and edit a three-word date field.  Here is how it works:
  357.  
  358.     CONST  fldDATE      =  ' WW-'^F^Z + ^U+char(12) + ^P+char(2) +
  359.                            #0'ZW-'^Z  + ^U+char(31) +
  360.                            #0'ZZZW '^Z^F + ^P+char(-6) +
  361.                            #0 + ^P+char(4);
  362.  
  363.       fldDATE defines what is called a "complex field".  The ^F control
  364.       code ensures that these three integer fields receive the same field
  365.       number.  The ^P code uses the next character to adjust the data
  366.       pointer forward 2 bytes, backward 6 bytes, and then 4 bytes forward
  367.       again.  This way, the YEAR-MONTH-DAY field can be displayed and
  368.       edited in MONTH-DAY-YEAR order, like this:  '  1-01-1992 '.
  369.       The ^U code is used to denote an upper limit for each field.
  370.       Refer to the section on control codes elsewhere in the documentation.
  371.  
  372.   These advanced features are demonstrated in program SAMPLES.PAS.
  373.  
  374.   ASCENDANCY CHART                                                    Page 7
  375.   ================
  376.  
  377.                               +-------------+
  378.                               |   TObject   |
  379.                               +-------------+
  380.                                      |
  381.                               +-------------+
  382.                               |    TView    |
  383.                               +-------------+
  384.                                      |
  385.                               +-------------+
  386.                               |  TScroller  |
  387.                               +-------------+
  388.                                      |
  389.                                      |
  390.                            +-------------------+
  391.                            |   TDmxScroller    |
  392.                            |   (unit tvDMX)    |
  393.                            +-------------------+
  394.                                      |
  395.                                      |
  396.                            +-------------------+
  397.                            |    TDmxEditor     |
  398.                            |   (unit tvDMX)    |
  399.                            +-------------------+
  400.                                      |
  401.                                      |
  402.                 +--------------------+--------------------+
  403.                 |                    |                    |
  404.                 |                    |                    |
  405.        +-----------------+  +-----------------+  +-----------------+
  406.        |   TDmxEditBuf   |  |  TDmxCollector  |  |   TDmxEditDlg   |
  407.        | (unit tvDMXBUF) |  | (unit tvDMXCOL) |  |  (unit StdDMX)  |
  408.        +-----------------+  +-----------------+  +-----------------+
  409.                 |                                         |
  410.           +-----+-------------+                  +-----------------+
  411.           |                   |                  |  TInputFields   |
  412.  +-----------------+ +-----------------+         |  (unit StdDMX)  |
  413.  | TDmxEditRecBuf  | |  TDmxStreamBuf  |         +-----------------+
  414.  | (unit tvDMXBUF) | | (unit tvDMXBUF) |
  415.  +-----------------+ +-----------------+
  416.                               |
  417.                      +-----------------+
  418.                      |   TDmxExpBuf    |
  419.                      | (unit tvDMXBUF) |
  420.                      +-----------------+
  421.  
  422.   UNITS                                                               Page 8
  423.   =====
  424.  
  425.  
  426.   Unit RSET contains untyped constants and data types.  No objects,
  427.   procedures, functions, or typed-constants are included.
  428.  
  429.  
  430.   Unit DMXGIZMA has a formatting function used internally by tvDMX and
  431.       defines the DMX-specific constants and types;
  432.  
  433.   Unit tvGIZMA has several objects and functions for Turbo Vision support;
  434.  
  435.  
  436.   Unit tvDMX contains:
  437.  
  438.       object TDmxLabels    --a view which displays field titles
  439.       object TDmxRecNum    --a view which displays the record number
  440.       object TDmxScroller  --the link between object TScroller and DMX
  441.       object TDmxEditor    --a data editor object
  442.  
  443.  
  444.   Unit StdDMX contains:
  445.  
  446.       object TDmxEditDlg   --TDmxEditor derivative for dialog boxes
  447.       object TInputFields  --TInputLine replacement for all data types
  448.  
  449.       object TDmxViewer    --TWindow descendant that initializes and
  450.                              INSERTs a TDmxScroller object
  451.       object TDmxWindow    --TDmxViewer descendant that initializes and
  452.                              INSERTs a TDmxEditor object
  453.  
  454.  
  455.   Unit tvDMXCOL contains:
  456.  
  457.       object TDmxCollector --TDmxEditor derivative for collections
  458.       object TDmxCollectorWin is a TDmxWindow derivative for TDmxCollector
  459.  
  460.  
  461.   Unit tvDMXBUF contains buffered tvDMX objects:
  462.  
  463.       object TDmxEditBuf   --TDmxEditor derivative for external data
  464.       object TDmxStreamBuf --TDmxEditBuf derivative for stream data
  465.       object TDmxExpBuf    --descendant of TDmxStreamBuf that expands as
  466.                              records are appended (see FILESHOP.PAS)
  467.  
  468.       objects TDmxBufWin and TDmxExpBufWin
  469.                            --TDmxWindow descendants for control of the
  470.                              previous two objects;
  471.  
  472.       object TDmxEditRecBuf -TDmxEditBuf descendant with NextRec and PrevRec
  473.                              abstract methods.
  474.  
  475.  
  476.   Unit tvDMXREP contains objects that output listings of tvDMX data.
  477.       Read file tvDMXREP.DOC for detailed information.
  478.  
  479.   DATA TEMPLATE CODES                                                 Page 9
  480.   ===================
  481.  
  482.  
  483.       Field codes:
  484.  
  485.            'S'  --STRING field
  486.            '#'  --STRING field (numbers only)
  487.            'C'  --CHARacter field (can be used for CHAR arrays)
  488.            '0'  --CHARacter field (numbers only)
  489.            'X'  --BOOLEAN value field
  490.            'B'  --BYTE field
  491.            'J'  --SHORTINT field
  492.            'W'  --WORD field
  493.            'I'  --INTEGER field
  494.            'L'  --LONGINT field
  495.            'R'  --REAL number field (uses TYPE TREALNUM in RSET.PAS)
  496.            'N'  --dBASE-formatted numeric CHAR field
  497.            'H'  --HEXadecimal numeric entry
  498.  
  499.  
  500.       Field code modifier:
  501.  
  502.            'Z'  --zero modifier to force leading zeroes
  503.  
  504.  
  505.       Field control codes:
  506.  
  507.            ^A   --show all zero values in all fields
  508.            ^D   --use the next character as a field delimiter
  509.            ^F   --start/end complex field
  510.            ^H   --hidden field
  511.            ^P   --display position modifier
  512.            ^R   --read-only field
  513.            ^S   --"skip" field (cursor will skip over it)
  514.            ^U   --set field's upperlimit (1 to 255 only)
  515.            ^V   --set field's default value
  516.            ^X   --special BOOLEAN field
  517.            ^Z   --show zeroes if this field is empty
  518.  
  519.            '~'  --switch string-literals on/off
  520.  
  521.  
  522.       Field Delimiters:
  523.  
  524.            #0   --technical field delimiter (not displayed)
  525.            '\'  --displayed as a space
  526.            '|'  --displayed as a solid vertical line (#179)
  527.            #179 or #186 may also be used as delimiters
  528.  
  529.                             Using Template Codes                     Page 10
  530.                             --------------------
  531.  
  532.   STRING Fields:
  533.  
  534.           's'       regular STRING field
  535.           'S'       STRING field (forces upper case)
  536.           '#'       STRING field (numbers only)
  537.  
  538.       These codes are used for normal Turbo Pascal STRING types.
  539.       If the '#' code is used then only spaces or numeric characters
  540.       ('0'..'9') can be entered.
  541.  
  542.       Examples:  'ssssssssssssssssssss'
  543.                  '~Name:~ SSSSSSSSSSSSSSSSSSSS'
  544.                  ' ###-##-#### '
  545.  
  546.  
  547.   CHAR Fields:
  548.  
  549.           'c'       CHAR field
  550.           'C'       CHAR field (forces upper case)
  551.           '0'       CHAR field (numbers only)
  552.  
  553.       Editing keys will operate in the same manner as STRING fields when
  554.       the field contains more than one character.  (Use these codes for
  555.       dBASE file structures.)
  556.       If the '0' code is used then only spaces or numeric characters
  557.       ('0'..'9') can be entered.
  558.  
  559.       Examples:  'C'
  560.                  'cccccccccccccccccccc'
  561.                  '~Name:~ CCCCCCCCCCCCCCCCCCCC'
  562.                  ' 000-00-0000 '
  563.  
  564.  
  565.   BOOLEAN Fields:
  566.  
  567.           'X'       regular BOOLEAN field
  568.           ^X        indicates special BOOLEAN field
  569.  
  570.       A regular BOOLEAN field will display the character ShowTRUE (as
  571.       defined in unit DMXGIZMA) or ShowFALSE, depending upon the value of
  572.       that field.  A special BOOLEAN field has no indicator of its own
  573.       but will display the template only if the data is TRUE.
  574.  
  575.       Examples:  'X'
  576.                  '[X]'
  577.                  '~TRUE~' + ^X
  578.  
  579.                                                                      Page 11
  580.   INTEGER Fields:
  581.  
  582.           'B'       BYTE field
  583.           'J'/'j'   SHORTINT field
  584.           'W'       WORD field
  585.           'I'/'i'   INTEGER field
  586.           'L'/'l'   LONGINT field
  587.  
  588.           'Z'/'z'   ZERO modifier to display leading zeroes
  589.  
  590.       The value of each field is limited to the natural limit of its
  591.       field TYPE, regardless of the displayed width of its template.
  592.       Upper case codes signify that negative numbers are not permitted.
  593.       (Case is not relevant for BYTE and WORD fields.)
  594.  
  595.       The 'Z' modifier can be used to force the display of a leading zero
  596.       as long as the data type is in one of the template characters.
  597.  
  598.       Examples:  'BBB'
  599.                  'WWWWW'
  600.                  'ZZZZW'
  601.                  'ii,iii'
  602.                  '%WZW'
  603.                  'LLL,LLL,LLL'
  604.  
  605.  
  606.   REAL Number Fields:
  607.  
  608.           'R'/'r'   REAL number field
  609.  
  610.       REAL numbers are declared like other numeric fields except that
  611.       parentheses '('/')' can be used to enclose the template.  These
  612.       will be displayed only if the value is a negative number.
  613.  
  614.       Floating point numbers other than of TYPE REAL can be used if
  615.       TYPE TREALNUM is changed in RSET.PAS.  (See RSET.PAS.)
  616.  
  617.       Examples:  '($rrr,rrr.rr)'
  618.                  'RRRRR.RRR'
  619.  
  620.  
  621.   Hexadecimal Fields:
  622.  
  623.           'H'       Hexadecimal numeric field
  624.  
  625.       Used for displaying and editing data in hexadecimal formats.  The
  626.       size and type of the field is dependent upon the number of H's.
  627.       This code is used extensively in unit tvDMXHEX.PAS.
  628.  
  629.       Examples:  'HH'
  630.                  'HHHH'
  631.                  'HHHH:HHHH'
  632.  
  633.                                                                      Page 12
  634.   dBASE-formatted numeric CHAR Fields:
  635.  
  636.           'n'       positive or negative values
  637.           'N'       positive values only
  638.  
  639.       These fields are stored as character arrays but are edited like
  640.       the numeric fields.  This may be formatted like any numeric field
  641.       except that parentheses cannot be used.
  642.       dBASE date fields can be formatted using 'Z' modifiers and a
  643.       system of ^P codes.  (See fldNDATE in FILESHOP.PAS.)
  644.  
  645.       Examples:  'nnn'
  646.                  'ZZN'
  647.                  'nnnnn.nnn'
  648.                  '$NNN,NNN.NN'
  649.  
  650.  
  651.                             Template Control Codes
  652.                             ----------------------
  653.  
  654.   Switch to Literals:
  655.  
  656.           '~'
  657.  
  658.       Switches DMX template interpretation to codes or literals.  This
  659.       permits all characters to be used in a template string.
  660.  
  661.       Examples:  '~Name:~ SSSSSSSSSSSSSSSSSSSS'
  662.                  '$RR,RRR.RR ~CR~'
  663.  
  664.  
  665.   Special Field Attributes:
  666.  
  667.           ^A        show zeroes in all fields
  668.           ^H        Hidden field
  669.           ^R        Read-Only field
  670.           ^S        Skip field (cursor will skip over it)
  671.           ^Z        show zeroes if this field is empty
  672.  
  673.       Every field has its own field-access attribute.  They may be
  674.       combined if desired.  ^A will function as a ^Z for each field.
  675.       Note that Hidden or Skip fields can still be zeroized when the
  676.       record is zeroized, unless it is also marked as Read-Only.
  677.  
  678.  
  679.   Define Template Delimiter:
  680.  
  681.           ^D + CHAR
  682.  
  683.       Uses the following character as a field delimiter.
  684.  
  685.       Examples:  ^D + '-'
  686.                  ^D + #255
  687.  
  688.                                                                      Page 13
  689.   Start/End Complex Field:
  690.  
  691.           ^F
  692.  
  693.       Begins or ends a complex field.  Each field within a complex field
  694.       is given the same field number so that the combined structure can
  695.       be treated as a singular item.
  696.  
  697.       Example:   ^F + ' BB | BB | WWWW ' + ^F
  698.  
  699.  
  700.   Position Modifier:
  701.  
  702.           ^P + CHAR
  703.  
  704.       Sets the position within the record (and also the record size) to
  705.       another point relative to the number of bytes indicated by the
  706.       SHORTINT value of the following character.  This is used by
  707.       fldDATE constant to swap the diplay positions of a date record from
  708.       Year-Month-Day to Month-Day-Year.
  709.       ^P can also be used as an alternative to hidden fields.
  710.  
  711.       Examples:  ^P + char(20)
  712.                  ^P + char(-4)
  713.  
  714.  
  715.   Set Field Upper Limit:
  716.  
  717.           ^U + CHAR
  718.  
  719.       The next character will be the field's upper limit (up to 255).
  720.       This is used by fldDATE to limit months to 12 and days to 31.
  721.  
  722.       Example:   ^U + char(12)
  723.  
  724.  
  725.   Set Field Default Value:
  726.  
  727.           ^V + CHAR
  728.  
  729.       The following character will be the field's default value, which
  730.       is set when it is zeroized.  Normally this would be zero for numerics
  731.       and spaces for character fields.
  732.  
  733.       Example:   ^V + '0'
  734.  
  735.   FYI                                                                Page 14
  736.   ===
  737.  
  738.  
  739.                           Important Virtual Methods
  740.                           -------------------------
  741.  
  742.     The following is a short list of some of the virtual methods that may
  743.     be overridden in descendant objects.
  744.  
  745.  
  746.   Function  TDmxEditor.DataAt (RecNum : integer)  : pointer;  VIRTUAL;
  747.  
  748.       Returns a pointer to the given data record.
  749.       By overriding this function, a program can alter the manner in which
  750.       the database is organized.  This method is used exclusively for data
  751.       retrieval --which gives programs the ability to access over 64k.
  752.  
  753.       The objects in unit tvDMXBUF.PAS override this method to retrieve data
  754.       records from external sources, but they use a buffer to store enough
  755.       data to reduce delay from disk access while scrolling.
  756.  
  757.       This object simply returns a pointer to the position in the database
  758.       from (RecNum * RecordSize).
  759.  
  760.  
  761.   Procedure TDmxEditor.EvaluateField;  VIRTUAL;
  762.  
  763.       Called AFTER each FIELD is edited.  It adjusts internal fields and
  764.       calls DrawField() to redraw the field in the regular color.
  765.       Programmers who wish to override this method should call its ancestor
  766.       in the descendant object.
  767.  
  768.  
  769.   Procedure TDmxEditor.EvaluateRecord;  VIRTUAL;
  770.  
  771.       Called AFTER each RECORD is edited.  The default method does nothing
  772.       and may be overrided entirely.
  773.  
  774.  
  775.   Procedure TDmxEditor.SetUpField;  VIRTUAL;
  776.  
  777.       Called BEFORE each FIELD is edited.  May call RecInd^.DrawView(), if
  778.       a record number indicator view is linked.
  779.       Programmers who wish to override this method should call its ancestor
  780.       in the descendant object.
  781.  
  782.  
  783.   Procedure TDmxEditor.SetUpRecord;  VIRTUAL;
  784.  
  785.       Called BEFORE each RECORD is edited.
  786.       This can be intercepted to display special information (eg: record
  787.       number) or to rearrange the record before editing.
  788.       Programmers who wish to override this method should call its ancestor
  789.       in the descendant object.
  790.  
  791.                                                                      Page 15
  792.  
  793.                            External Database Access
  794.                            ------------------------
  795.  
  796.     TDmxEditBuf is a descendant of TDmxEditor that uses a circular buffer
  797.     to edit data from a source other than in RAM.  This can be overridden
  798.     to access your own database library procedures.
  799.  
  800.     It retrieves each record individually when accessed.  The buffer is
  801.     used only for quick page draws.
  802.  
  803.     This object can be found in unit tvDMXBUF.  It uses several abstract
  804.     methods and must not be instantiated as is.  Objects TDmxStreamBuf and
  805.     TDmxExpBuf are usable descendants.  Object TDmxExpBuf is demonstrated
  806.     in program FILESHOP.PAS.
  807.  
  808.     Descendants MUST override functions SeekRec(), ReadRec() and WriteRec():
  809.  
  810.  
  811.   Function  TDmxEditBuf.SeekRec (RecNum : integer) : boolean;  VIRTUAL;
  812.       Override: Always
  813.  
  814.       This abstract virtual method is called before reading or writing a
  815.       record.  It must seek to the given record position.  It is important
  816.       that you remember that the first record is numbered 0.
  817.       It should seek to RecNum+1 if the database is structured with record
  818.       number 1 as the first record.
  819.  
  820.  
  821.   Function  TDmxEditBuf.ReadRec (var RecData ) : boolean;  VIRTUAL;
  822.       Override: Always
  823.  
  824.       Abstract virtual method called to retrieve record RecData.  It must
  825.       return a record exactly the size that is determined by the template.
  826.  
  827.  
  828.   Function  TDmxEditBuf.WriteRec (var RecData ) : boolean;  VIRTUAL;
  829.       Override: Always
  830.  
  831.       Abstract virtual method called by EvaluateRecord() to store record
  832.       RecData if a change was made.
  833.  
  834.  
  835.     These functions must perform their record operations at the current
  836.     record position and return TRUE if the operation succeeded or FALSE if
  837.     it failed.  It is the programmer's responsibility to retain the error
  838.     code for use by the ErrorFunc() method.
  839.  
  840.     TDmxEditBuf.ErrorFunc() is a virtual method that may be overridden for
  841.     special handling of database errors.
  842.  
  843.     Please refer to file tvDMXBUF for more information.
  844.  
  845.                                                                      Page 16
  846.  
  847.                 Global Functions in Units DMXGIZMA and tvGIZMA
  848.                 ----------------------------------------------
  849.  
  850.  
  851.   Procedure AssignWinRect (var Bounds : TRect;  MaxX, MaxY : integer);
  852.  
  853.       Assigns Bounds to fit into the desktop, with MaxX and MaxY as the
  854.       maximum desired width and height.  Bounds is cut and moved to a
  855.       cascaded position behind the currently active window.  (This is
  856.       similar to what happens when a new file is loaded into the TP IDE.)
  857.  
  858.  
  859.   Function  DmxStrLen (S : string)  : integer;
  860.  
  861.       Returns the length of the visible portions of a template string.
  862.       (From unit DMXGIZMA)
  863.  
  864.  
  865.   Function  NextWindowNumber  : integer;
  866.  
  867.       Returns the next available (unused) window number.
  868.  
  869.  
  870.   Procedure TrimDialog (Window : PWindow);
  871.  
  872.       Shrinks and centers a dialog window to ease the design process.
  873.       The dialog window should be initialized with the maximum size
  874.       allowable.  TrimDialog() can be called after the controls are
  875.       inserted to resize the window down to the maximum size needed.
  876.       See program DLGSHOP.PAS for sample usage.
  877.  
  878.  
  879.   TAppA        =  OBJECT (TProgram)
  880.  
  881.       TApplication replacement that initializes TV's major components
  882.       after saving the original user screen.  It provides for handling
  883.       of the following command events:  cmDMX_WrongKey, cmUserScreen,
  884.       cmToggleSound, cmToggleVideo, cmCascade and cmTile.
  885.  
  886.  
  887.   TCursorDlg   =  OBJECT (TDialog)
  888.  
  889.       Dialog object class that allows buttons, input lines, and other
  890.       controls to react to unwanted up, down, right, and left cursor keys.
  891.  
  892.  
  893.   TUserScreen  =  OBJECT (TScroller)
  894.  
  895.       Scroller object that displays the original user screen that has been
  896.       saved by the TAppA.Init() constructor.
  897.  
  898.   USER RESPONSE FORM                                                 Page 17
  899.   ==================
  900.  
  901.     If you have a printer:  Please take a few moments to complete
  902.     as much of this form as possible.  File REGISTER.TXT contains
  903.     a separate copy of this text.
  904.  
  905.     (Registered users can upgrade to this version free, and should
  906.     not register again.)
  907.  
  908.  
  909.         Name    _____________________________________________
  910.         Company _____________________________________________
  911.         Address _____________________________________________
  912.         City    ____________________________, State _________
  913.         Zip     ____________________________
  914.  
  915.  
  916.     How long have you been using Turbo Vision? ______
  917.  
  918.     Which version of Turbo Pascal are you using? _____
  919.  
  920.     List any programming tools/add-ins that you use:
  921.       ___ AnsiView
  922.       ___ Blaise: ________________________________________
  923.       ___ Btrieve
  924.       ___ DMX (original for TP 5.5) --upgrade fee only $10
  925.       ___ Paradox Engine
  926.       ___ Topaz
  927.       ___ TurboPower: ____________________________________
  928.  
  929.       Others:
  930.  
  931.  
  932.     Print this form and send it with $20 registration fee to:
  933.  
  934.                    Randolph Beck
  935.                    tvDMX Registration
  936.                    P.O. Box  56-0487
  937.                    Orlando, FL  32856-0487
  938.  
  939.     ----------------------------------------------------------------------
  940.  
  941.     Add any additional questions or comments...
  942.  
  943.  
  944.          ----------------end-of-author's-documentation---------------
  945.  
  946.                          Software Library Information:
  947.  
  948.                     This disk copy provided as a service of
  949.  
  950.                            Public (software) Library
  951.  
  952.          We are not the authors of this program, nor are we associated
  953.          with the author in any way other than as a distributor of the
  954.          program in accordance with the author's terms of distribution.
  955.  
  956.          Please direct shareware payments and specific questions about
  957.          this program to the author of the program, whose name appears
  958.          elsewhere in  this documentation. If you have trouble getting
  959.          in touch with the author,  we will do whatever we can to help
  960.          you with your questions. All programs have been tested and do
  961.          run.  To report problems,  please use the form that is in the
  962.          file PROBLEM.DOC on many of our disks or in other written for-
  963.          mat with screen printouts, if possible.  PsL cannot debug pro-
  964.          programs over the telephone, though we can answer questions.
  965.  
  966.          Disks in the PsL are updated  monthly,  so if you did not get
  967.          this disk directly from the PsL, you should be aware that the
  968.          files in this set may no longer be the current versions. Also,
  969.          if you got this disk from another vendor and are having prob-
  970.          lems,  be aware that  some files may have become corrupted or
  971.          lost by that vendor. Get a current, working disk from PsL.
  972.  
  973.          For a copy of the latest monthly software library newsletter
  974.          and a list of the 4,000+ disks in the library, call or write
  975.  
  976.                            Public (software) Library
  977.                                P.O.Box 35705 - F
  978.                             Houston, TX 77235-5705
  979.  
  980.                                 1-800-2424-PSL
  981.                              MC/Visa/AmEx/Discover
  982.  
  983.                           Outside of U.S. or in Texas
  984.                           or for general information,
  985.                               Call 1-713-524-6394
  986.  
  987.  
  988.